<html><!-- Created using the cpp_pretty_printer from the dlib C++ library.  See http://dlib.net for updates. --><head><title>dlib C++ Library - roc_trainer_abstract.h</title></head><body bgcolor='white'><pre>
<font color='#009900'>// Copyright (C) 2009  Davis E. King (davis@dlib.net)
</font><font color='#009900'>// License: Boost Software License   See LICENSE.txt for the full license.
</font><font color='#0000FF'>#undef</font> DLIB_ROC_TRAINEr_ABSTRACT_
<font color='#0000FF'>#ifdef</font> DLIB_ROC_TRAINEr_ABSTRACT_

<font color='#0000FF'>#include</font> "<a style='text-decoration:none' href='../algs.h.html'>../algs.h</a>"

<font color='#0000FF'>namespace</font> dlib
<b>{</b>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> trainer_type 
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'>class</font> <b><a name='roc_trainer_type'></a>roc_trainer_type</b>
    <b>{</b>
        <font color='#009900'>/*!
            REQUIREMENTS ON trainer_type
                - trainer_type == some kind of batch trainer object (e.g. svm_nu_trainer)

            WHAT THIS OBJECT REPRESENTS
                This object is a simple trainer post processor that allows you to 
                easily adjust the bias term in a trained decision_function object.
                That is, this object lets you pick a point on the ROC curve and 
                it will adjust the bias term appropriately.  

                So for example, suppose you wanted to set the bias term so that
                the accuracy of your decision function on +1 labeled samples was 99%.
                To do this you would use an instance of this object declared as follows:
                    roc_trainer_type&lt;trainer_type&gt;(your_trainer, 0.99, +1);
        !*/</font>

    <font color='#0000FF'>public</font>:
        <font color='#0000FF'>typedef</font> <font color='#0000FF'>typename</font> trainer_type::kernel_type kernel_type;
        <font color='#0000FF'>typedef</font> <font color='#0000FF'>typename</font> trainer_type::scalar_type scalar_type;
        <font color='#0000FF'>typedef</font> <font color='#0000FF'>typename</font> trainer_type::sample_type sample_type;
        <font color='#0000FF'>typedef</font> <font color='#0000FF'>typename</font> trainer_type::mem_manager_type mem_manager_type;
        <font color='#0000FF'>typedef</font> <font color='#0000FF'>typename</font> trainer_type::trained_function_type trained_function_type;

        <b><a name='roc_trainer_type'></a>roc_trainer_type</b> <font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            ensures
                - This object is in an uninitialized state.  You must
                  construct a real one with the other constructor and assign it
                  to this instance before you use this object.
        !*/</font>

        <b><a name='roc_trainer_type'></a>roc_trainer_type</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'>const</font> trainer_type<font color='#5555FF'>&amp;</font> trainer_,
            <font color='#0000FF'>const</font> scalar_type<font color='#5555FF'>&amp;</font> desired_accuracy_,
            <font color='#0000FF'>const</font> scalar_type<font color='#5555FF'>&amp;</font> class_selection_
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            requires
                - 0 &lt;= desired_accuracy_ &lt;= 1
                - class_selection_ == +1 or -1
            ensures
                - when training is performed using this object it will automatically
                  adjust the bias term in the returned decision function so that it
                  achieves the desired accuracy on the selected class type.
        !*/</font>

        <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
            <font color='#0000FF'>typename</font> in_sample_vector_type,
            <font color='#0000FF'>typename</font> in_scalar_vector_type
            <font color='#5555FF'>&gt;</font>
        <font color='#0000FF'>const</font> trained_function_type <b><a name='train'></a>train</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'>const</font> in_sample_vector_type<font color='#5555FF'>&amp;</font> samples,
            <font color='#0000FF'>const</font> in_scalar_vector_type<font color='#5555FF'>&amp;</font> labels
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> 
        <font color='#009900'>/*!
            requires
                - is_binary_classification_problem(samples, labels) == true
                - x == a matrix or something convertible to a matrix via mat().
                  Also, x should contain sample_type objects.
                - y == a matrix or something convertible to a matrix via mat().
                  Also, y should contain scalar_type objects.
            ensures
                - performs training using the trainer object given to this object's 
                  constructor, then modifies the bias term in the returned decision function
                  as discussed above, and finally returns the decision function.
        !*/</font>

    <b>}</b>; 

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> trainer_type
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'>const</font> roc_trainer_type<font color='#5555FF'>&lt;</font>trainer_type<font color='#5555FF'>&gt;</font> <b><a name='roc_c1_trainer'></a>roc_c1_trainer</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'>const</font> trainer_type<font color='#5555FF'>&amp;</font> trainer,
        <font color='#0000FF'>const</font> <font color='#0000FF'>typename</font> trainer_type::scalar_type<font color='#5555FF'>&amp;</font> desired_accuracy
    <font face='Lucida Console'>)</font> <b>{</b> <font color='#0000FF'>return</font> roc_trainer_type<font color='#5555FF'>&lt;</font>trainer_type<font color='#5555FF'>&gt;</font><font face='Lucida Console'>(</font>trainer, desired_accuracy, <font color='#5555FF'>+</font><font color='#979000'>1</font><font face='Lucida Console'>)</font>; <b>}</b>
    <font color='#009900'>/*!
        requires
            - 0 &lt;= desired_accuracy &lt;= 1
            - trainer_type == some kind of batch trainer object that creates decision_function
              objects (e.g. svm_nu_trainer)
        ensures
            - returns a roc_trainer_type object that has been instantiated with the given 
              arguments.  The returned roc trainer will select the decision function
              bias that gives the desired accuracy with respect to the +1 class.
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> trainer_type
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'>const</font> roc_trainer_type<font color='#5555FF'>&lt;</font>trainer_type<font color='#5555FF'>&gt;</font> <b><a name='roc_c2_trainer'></a>roc_c2_trainer</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'>const</font> trainer_type<font color='#5555FF'>&amp;</font> trainer,
        <font color='#0000FF'>const</font> <font color='#0000FF'>typename</font> trainer_type::scalar_type<font color='#5555FF'>&amp;</font> desired_accuracy
    <font face='Lucida Console'>)</font> <b>{</b> <font color='#0000FF'>return</font> roc_trainer_type<font color='#5555FF'>&lt;</font>trainer_type<font color='#5555FF'>&gt;</font><font face='Lucida Console'>(</font>trainer, desired_accuracy, <font color='#5555FF'>-</font><font color='#979000'>1</font><font face='Lucida Console'>)</font>; <b>}</b>
    <font color='#009900'>/*!
        requires
            - 0 &lt;= desired_accuracy &lt;= 1
            - trainer_type == some kind of batch trainer object that creates decision_function
              objects (e.g. svm_nu_trainer)
        ensures
            - returns a roc_trainer_type object that has been instantiated with the given 
              arguments.  The returned roc trainer will select the decision function
              bias that gives the desired accuracy with respect to the -1 class.
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
<b>}</b>

<font color='#0000FF'>#endif</font> <font color='#009900'>// DLIB_ROC_TRAINEr_ABSTRACT_
</font>



</pre></body></html>